---
title: MCP Server
edit-this-page-url: https://github.com/airweave-ai/airweave/blob/main/fern/docs/pages/mcp-server.mdx
subtitle: Serve your Airweave collection through an MCP server so that clients such as Cursor, Claude or VS Code can query it directly.
slug: mcp-server
---

### Prerequisites

Before you start you’ll need:

  - **A collection with data**: at least one source connection must have completed its initial sync. See the [Quickstart](https://docs.airweave.ai/quickstart) if you need to set this up.
  - **An API key**: Create one in the Airweave dashboard under **API Keys**.

### Set-up


<Tabs>
    <Tab title="Cursor">
      > **Requirement**: Cursor version 0.45.6 or later

      1. Open **Cursor Settings**
      2. Go to **Features > MCP Servers**
      3. Click **"+ Add new global MCP server"**
      4. Add this configuration:

      ```json title="Cursor Configuration"
      {
        "mcpServers": {
          "airweave-search": {
            "command": "npx",
            "args": ["-y", "airweave-mcp-search"],
            "env": {
              "AIRWEAVE_API_KEY": "your-api-key",
              "AIRWEAVE_COLLECTION": "your-collection-id"
            }
          }
        }
      }
      ```
    </Tab>

    <Tab title="Claude Desktop">
      Add the following to your Claude Desktop config file and restart Claude Desktop afterwards.
      After a restart the search tool will appear in Claude’s composer.

        - **macOS/Linux**: `~/.claude/claude_desktop_config.json`
        - **Windows**: `%APPDATA%\claude\claude_desktop_config.json`

      ```json title="Claude Desktop Configuration"
      {
        "mcpServers": {
          "airweave-search": {
            "command": "npx",
            "args": ["-y", "airweave-mcp-search"],
            "env": {
              "AIRWEAVE_API_KEY": "your-api-key",
              "AIRWEAVE_COLLECTION": "your-collection-id"
            }
          }
        }
      }
      ```
    </Tab>

    <Tab title="VS Code">
      Add to your User Settings (JSON) via **Ctrl+Shift+P** → **"Preferences: Open User Settings (JSON)"**:

      ```json title="VS Code Configuration"
      {
        "mcp": {
          "inputs": [
            {
              "type": "promptString",
              "id": "airweaveApiKey",
              "description": "Airweave API Key",
              "password": true
            },
            {
              "type": "promptString",
              "id": "airweaveCollection",
              "description": "Airweave Collection ID"
            }
          ],
          "servers": {
            "airweave": {
              "command": "npx",
              "args": ["-y", "airweave-mcp-search"],
              "env": {
                "AIRWEAVE_API_KEY": "${input:airweaveApiKey}",
                "AIRWEAVE_COLLECTION": "${input:airweaveCollection}"
              }
            }
          }
        }
      }
      ```
    </Tab>
  </Tabs>

These environment variables can be set:

  - `AIRWEAVE_API_KEY` (Required): Authenticates the MCP server with the Airweave API so it can run searches on your behalf.
  - `AIRWEAVE_COLLECTION` (Required): Readable ID of the collection to query. All `search` calls are scoped to this collection.
  - `AIRWEAVE_BASE_URL` (Optional): Override if you're running a self-hosted Airweave instance (default: `https://api.airweave.ai`).

### Available tools

The MCP server provides two tools:

  - **search**: Enhanced search across all source connections in the collection with full parameter control and optional AI completion.
  - **get-config**: View current configuration and connection status so you can verify everything is working correctly. No parameters required.

### Advanced Search Features

The search tool uses the **POST** endpoint for full control over search parameters.

**Available Parameters:**
- `retrieval_strategy`: Choose between 'hybrid', 'neural', or 'keyword' search (default: 'hybrid')
- `expand_query`: Generate query variations for better recall (default: true)
- `interpret_filters`: Extract filters from natural language (default: false)
- `rerank`: LLM-based result reranking for improved relevance (default: true)
- `generate_answer`: AI-generated completion from results (default: true)
- `temporal_relevance`: Recency weighting from 0.0 to 1.0 (default: 0.3)
- `limit`: Maximum number of results (default: 1000)
- `offset`: Pagination offset (default: 0)

**Natural Language Examples:**
- "Use neural search for semantic similarity" → `retrieval_strategy: "neural"`
- "Search without expanding the query" → `expand_query: false`
- "Extract filters from my query" → `interpret_filters: true`
- "Disable reranking for faster results" → `rerank: false`
- "Just return results, no AI summary" → `generate_answer: false`
- "Prioritize recent documents" → `temporal_relevance: 0.8`
